[iOS][Swift] 「Jazzy」を使ってSwiftのソースファイルからドキュメントを生成する

加藤潤

2018.03.19

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

こんにちは。加藤です。「Jazzy」。その存在は前から知ってはいたものの、実際に使用する場面が無く、これまで使ったことはありませんでした。しかしながら今回使う機会がありましたので忘れないように記録に残しておきます。

Jazzyとは

Jazzyとは、SwiftやObjective-Cのドキュメントを生成するツールです。
以下はリポジトリのREADMEからの引用です。

jazzy is a command-line utility that generates documentation for Swift or Objective-C

モバイルデータベースで有名なRealmによって管理されており、MITライセンスで公開されています。

検証環境

本エントリは以下の環境で検証を行っています。

macOS High Sierra バージョン 10.13.3
Xcode Version 9.2 (9C40b)
Swift 4
Jazzy 0.9.1
CocoaPods 1.3.1

ここではあるiOSアプリを作成していて、ライブラリ管理にはCocoaPodsを使用しているとしましょう。プロジェクト名は今回「JazzySample」としました。 CocoaPodsでライブラリをインストールすると、以下のようにxcworkspaceファイルが生成されているでしょう。

ソースファイル

今回はドキュメント生成結果を確認するために、以下のファイルを作成しました。


import Foundation

/// ユーザーのリポジトリ
class UserRepository {

    /// IDを指定してユーザーを取得する。
    ///
    /// - Parameter identifier: ユーザーID
    /// - Returns: ユーザー
    func find(byIdentifier identifier: String) -> User {
        // TODO: impl
        return User(identifier: "1", name: "kato")
    }

    /// プライベート関数
    private func pFunc() {
    }
}

import Foundation

/// ユーザー
struct User {

    /// ID
    let identifier: String

    /// 名前
    let name: String
}

使ってみた

Jazzyのインストール

以下のコマンドを実行してインストールします。

[sudo] gem install jazzy

jazzy -h でオプションの説明が見れる

jazzyには非常に豊富な実行オプションがあるため、 jazzy -hコマンドを実行して、自分の環境に関係ありそうなオプションをざっと眺めておくといいかと思います。

Usage: jazzy

Options
-o, --output FOLDER Folder to output the HTML docs to
-c, --[no-]clean Delete contents of output directory before running.
WARNING: If --output is set to ~/Desktop, this will delete the ~/Desktop directory.
--[no-]objc Generate docs for Objective-C.
--umbrella-header PATH Umbrella header for your Objective-C framework.
--framework-root PATH The root path to your Objective-C framework.
--sdk [iphone|watch|appletv][os|simulator]|macosx
The SDK for which your code should be built.
--hide-declarations
Hide declarations in the specified language. Given that generating Swift docs only generates Swift declarations, this is only really useful to display just the Swift declarations & names when generating docs for an Objective-C framework.
--config PATH Configuration file (.yaml or .json)
Default: .jazzy.yaml in source directory or ancestor
-x arg1,arg2,…argN, Arguments to forward to xcodebuild
--xcodebuild-arguments
-s FILEPATH, File generated from sourcekitten output to parse
--sourcekitten-sourcefile
--source-directory DIRPATH The directory that contains the source to be documented
-e filepath1,filepath2,…filepathN,
--exclude Source file pathnames to be excluded from documentation. Supports wildcards.
--swift-version VERSION
-a, --author AUTHOR_NAME Name of author to attribute in docs (e.g. Realm)
-u, --author_url URL Author URL of this project (e.g. http://realm.io)
-m, --module MODULE_NAME Name of module being documented. (e.g. RealmSwift)
--module-version VERSION module version. will be used when generating docset
--copyright COPYRIGHT_MARKDOWN
copyright markdown rendered at the bottom of the docs pages
--readme FILEPATH The path to a markdown README file
--documentation GLOB Glob that matches available documentation
--abstract GLOB Glob that matches available abstracts for categories
--podspec FILEPATH A CocoaPods Podspec that describes the Swift library to document
--docset-icon FILEPATH
--docset-path DIRPATH The relative path for the generated docset
-r, --root-url URL Absolute URL root where these docs will be stored
-d, --dash_url URL Location of the dash XML feed e.g. http://realm.io/docsets/realm.xml)
-g, --github_url URL GitHub URL of this project (e.g. https://github.com/realm/realm-cocoa)
--github-file-prefix PREFIX GitHub URL file prefix of this project (e.g. https://github.com/realm/realm-cocoa/tree/v0.87.1)
--disable-search Avoid generating a search index. Search is available in some themes.
--skip-documentation Will skip the documentation generation phase.
--min-acl [private | fileprivate | internal | public | open]
minimum access control level to document
--[no-]skip-undocumented Don't document declarations that have no documentation comments.
--[no-]hide-documentation-coverage
Hide "(X% documented)" from the generated documents
--head HTML Custom HTML to inject into <head></head>.
--theme [apple | fullwidth | DIRPATH]
Which theme to use. Specify either 'apple' (default), 'fullwidth' or the path to your mustache templates and other assets for a custom theme.
--use-safe-filenames Replace unsafe characters in filenames with an encoded representation. This will reduce human readability of some URLs, but may be necessary for projects that expose filename-unfriendly functions such as /(_:_:)
-t, --template-directory DIRPATH DEPRECATED: Use --theme instead.
--assets-directory DIRPATH DEPRECATED: Use --theme instead.
--undocumented-text UNDOCUMENTED_TEXT
Default text for undocumented symbols. The default is "Undocumented", put "" if no text is required
-v, --version Print version number
-h, --help [TOPIC] Available topics:
usage Command line options (this help message)
config Configuration file options
...or an option keyword, e.g. "dash"

コマンドラインで生成する

まずは基本。コマンドラインで生成してみましょう。以下のコマンドをプロジェクトのルートディレクトリで実行してみました。

jazzy --min-acl internal \
-c  \
-o docs \
--author kato  \
--author_url https://dev.classmethod.jp/ \
--module JazzySample \
--xcodebuild-arguments -workspace,JazzySample.xcworkspace,-scheme,JazzySample

以下、オプションの説明です。

min-ac
- minimum access control level。[private | fileprivate | internal | public | open]
- ここで指定したレベル以上がドキュメント化される。別の言い方をすると、ここで指定したレベルより厳しいレベルについてはドキュメント化されない。
c
- 実行前に出力先フォルダをクリーンする。
o
- ドキュメント出力先フォルダの指定
author
- 著者
author_url
- 著者のURL
module
- ドキュメント化するモジュールの名前
xcodebuild-arguments
- xcodebuildへ渡すパラメータ。カンマ区切りで指定する。

結果はこちら。htmlやらjsonが生成されました。

index.htmlを開いてみましょう。
おぉ、ちゃんとドキュメント生成されてますね〜！！今回はmin-acにinternalを指定したのでprivateな関数はドキュメントに含まれていないですね。すごい。

設定ファイルを用意して生成する

上述のようにコマンドラインでオプションを指定して実行できますが、別途オプションを記載したyamlファイルを用意して実行することもできます。指定するオプションが多い場合や、設定ファイルもgit等で管理したい場合はyamlファイルを使用した方が良いでしょう。デフォルトで、.jazzy.yamlというファイルを用意しておけば設定を読み込んでくれるようになっています。

コマンドラインで実行した内容を.jazzy.yamlにしたものが以下です。


# minimum access control level。[private | fileprivate | internal | public | open]
# ここで指定したレベル以上がドキュメント化される。別の言い方をすると、ここで指定したレベルより厳しいレベルについてはドキュメント化されない。
min_acl: internal

#実行前に出力先フォルダをクリーン
clean: true

# ドキュメント出力先フォルダ
output: docs

# 著者
author: kato

# 著者のURL
author_url: https://dev.classmethod.jp

# ドキュメント化するモジュールの名前
module: JazzySample

# xcodebuildの引数
xcodebuild_arguments: [-workspace,JazzySample.xcworkspace,-scheme,JazzySample]

.jazzy.yamlをプロジェクトのルートディレクトリに配置し、jazzyコマンドを実行します。
以下のように.jazzy.yamlの設定を使用してドキュメントを生成してくれます。

まとめ「めちゃめちゃ便利なドキュメント生成ツール」

簡単にドキュメント生成できて、オプションも豊富で、設定ファイルに記述できて、もうめちゃめちゃ便利ですね。生成されるモジュールが複数あるプロジェクトの場合はモジュール名を忘れずに指定するようにしてください。うまくドキュメントが生成されない場合は、まずxcodebuild単体で実行してみるといいと思います。
xcodebuildが成功するかどうかでxcodebuild_argumentsの指定が正しいかどうかの切り分けができるのでお試しください。